{% extends "base.html" %}

{% block title %} api documentation - {{block.super}}{% endblock %}

{% block content %}

<h1>REST API Documentation</h1>

{% comment %}
{% for doc in docs %}
<h2>{{doc.name}}</h2>
<dl>
    {% for meth in doc.methods %}
    <dt><strong>{{meth.name}}</strong>(<em>{{meth.sig2}}</em>):</dt>
    <dd>{{meth.doc}}</dd>
    {% endfor %}
</dl>
{% endfor %}
{% endcomment %}



<h2>Usage</h2>
<p>
To use the 
<a href="http://en.wikipedia.org/wiki/Representational_State_Transfer" 
   title="Representational State Transfer">REST</a> 
api of {{cur_site}}
use http request methods GET, POST, PUT and DELETE to get, create, update or
delete an object. Currently you can read and edit projects and releases. <br/>
For some small read requests, have a look at the even simpler <a href="{% url xmlrpc %}">XML-RPC api</a>.
<h3>URLs</h3>
Prefix an objects url with "/api" to get the REST api url. Add a format string
to set the format of return values. Allowed formats are: "xml", "json", "yaml",
"pickle", "django".
<dl>
<dt>Projects:</dt>
  <dd>http://{{cur_site}}/api/projects/{project slug}/{format}/</dd>
<dt>Releases:</dt>
  <dd>http://{{cur_site}}/api/projects/{project slug}/{release slug}/{format}/</dd>
</dl>
</p>

<h2>Example</h2>

{% code %}
import urllib2
import urllib

theurl = 'http://{{cur_site}}/api/projects/myproject/xml/'
username = 'yourusername'
password = 'yourpassword'


class RequestWithMethod(urllib2.Request):
    def __init__(self, method, *args, **kwargs):
        self._method = method
        urllib2.Request.__init__(self, *args, **kwargs)

    def get_method(self):
        return self._method



# anonymous: "read" a project

pagehandle = urllib2.urlopen(RequestWithMethod("GET", theurl, ""))
content = pagehandle.read()
print content



# authenticated: update a project

passman = urllib2.HTTPPasswordMgrWithDefaultRealm()
passman.add_password(None, theurl, username, password)
authhandler = urllib2.HTTPBasicAuthHandler(passman)
opener = urllib2.build_opener(authhandler)

urllib2.install_opener(opener)



data = urllib.urlencode([('summary', 'mynewsummary'), ("members", "staff")])
pagehandle = urllib2.urlopen(RequestWithMethod("PUT", theurl, data))
content = pagehandle.read()
print content
{% endcode %}

{% endblock %} 